/*
 * Copyright (C) 2009 M. Hautle.
 * 
 * This file is part of TrackedBean.
 * 
 * TrackedBean is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option) any later version.
 * 
 * TrackedBean is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License along with TrackedBean. If not, see <http://www.gnu.org/licenses/>.
 */
package ch.trackedbean.copier;

/**
 * Context used in {@link IBeanMapper}.
 * 
 * @author M. Hautle
 */
public interface IMappingContext {
	/**
	 * Returns true if the property represented by the given holder should be copied.<br>
	 * This check is for {@link IBeanMapper#copySrc2Dst(Object, Object, IMappingContext)}
	 * 
	 * @param holder The mapping to check
	 * @return True if the value should be copied
	 */
	boolean copySrc2Dst(IMappingHolder holder);

	/**
	 * Returns true if the property represented by the given holder should be copied.<br>
	 * This check is for {@link IBeanMapper#copyDst2Src(Object, Object, IMappingContext)}
	 * 
	 * @param holder The mapping to check
	 * @return True if the value should be copied
	 */
	boolean copyDst2Src(IMappingHolder holder);

	/**
	 * Looks up a previously converted/mapped instance (previously stored using {@link #putElement(Object, Object)}).
	 * 
	 * @param <T> The desired type
	 * @param key The source instance
	 * @param type The desired type
	 * @return The converted instance or null
	 */
	<T> T getElement(Object key, Class<T> type);

	/**
	 * Stores a converted/mapped instance for the given source element.<br>
	 * Use {@link #getElement(Object, Class)} to retrive the stored instances.
	 * 
	 * @param <T> The type of the value
	 * @param key The source instance
	 * @param value The converted instance
	 * @return The converted instance
	 */
	<T> T putElement(Object key, T value);

	/**
	 * Returns the value for the given key (previously stored using {@link #putValue(Object, Object)}).
	 * 
	 * @param <T> The type
	 * @param key The key
	 * @return The value for the given key or null
	 */
	<T> T getValue(Object key);

	/**
	 * Stores the given value using the passed key.<br>
	 * Stored value can be retrived using {@link #getValue(Object)}.
	 * 
	 * @param key The key
	 * @param value The value
	 * @return The previously value of the specified key
	 */
	Object putValue(Object key, Object value);
}
